Task Transactions

vFire has two Application Programming Interfaces (or APIs), which enable you to develop programs that automate many common vFire transactions. This section of the documentation deals with the Classic API. For more information on the RESTful Alemba API, introduced in 9.7, see here.

The API provides transactions in which to update, retrieve, forward and complete tasks. Tasks themselves cannot be created through the API.

Timesheet transactions are provided for updating existing tasks.

Availability transactions are provided to find outages linked to existing tasks.

There is a transaction to pass a list of CMDB Items against which an outage can be created. If possible, the API will create an outage against the specified items.  If the transaction is unable to create an outage against the specified item, it may return an error.

TaskUpdate Transaction

The TaskUpdate transaction can be used to update an existing task. However, you cannot create tasks using the API.

Input Parameters: TaskUpdateRequest

Argument

Type

Mandatory

Default

Description

sID

String

No. See Transaction Login.

“”

Analyst’s current Session ID

sLoginUserID

String

No. See Transaction Login.

“”

Analyst’s Login ID

sLoginPassword

String

No. See Transaction Login.

“”

Analyst’s Password

sDatabase

String

No. See Transaction Login.

“”

Name of the vFire system for logging in.

lEntityRef

Lookup Field

Yes

-

Reference number of the task to update

sTitle

String

No

(As is)

Task Title

nOrder

Integer

No

(As is)

Task Order

lType

Lookup Field

No

(As is)

Task Type

lPriority

Lookup Field

No

(As is)

Task Priority

lPhase

Lookup Field

No

(As is)

Task Phase

dPlannedStart

Date/Time

No

(As is)

Task Planned Start Date

nPlannedTimeHrs

Integer

No

(As is)

Task Planned Time (hours)

nPlannedTimeMins

Integer

No

(As is)

Task Planned Time (minutes)

dTargetDate

Date/Time

No

(As is)

Task Target Date

lFwdOfficer

Lookup Field

No

0

Analyst to which to assign the task

yAutoCalculate

Yes/No

No

N

Flag whether to autocalculate Task target date. Values:

  • Y = automatically calculate task target date
  • N = do not automatically calculate task target date

yRecalculateDependent

Yes/No

No

N

Flag whether to recalculate dates on dependent tasks. Values:

  • Y = recalculate dependent tasks
  • N = do not recalculate dependent tasks

lActionType

Lookup Field

No

0

Action & Solution Type

lFwdGroup

Lookup Field

No

0

Group to which to forward the task

dActionStart

Date/Time

No

Now

Action & Solution start date

dActionEnd

Date/Time

No

Now

Action & Solution end date

nActionTimeHrs

Integer

No

Uses the difference between the Action Start and Action End

Action & Solution recorded time spent

nActionTimeMins

Integer

No

Uses the difference between the Action Start and Action End

Action & Solution recorded time spent

lTaskStatus

Lookup Field

No

0

Task Status

lSecurity

Lookup Field

No

0

Security Profile to apply to the Action & Solution

sReason

String

No

“”

Audit reason

bSendEmail

Boolean

No

False

Flag whether to send an email to the task assigned analyst/group. Values:

  • True = send an email to the assigned analyst/group
  • False = do not send an email to the assigned analyst/group

bSendPager

Boolean

No

False

Flag whether to send a pager message to the task assigned analyst/group. Values:

  • True = send a pager message to the assigned analyst/group
  • False = do not send a pager message to the assigned analyst/group

aCustomParameters

Array

No

“”

See Defining Custom Parameters.

Return Values: TaskResponse

Argument

Type

Description

nEntityRef

Integer

Task number

sMessage

String

Error/Warning Message

Ret

APIReturn

Error/Warning Number

TaskRetrieve Transaction

The TaskRetrieve transaction can be used to retrieve an existing task’s details.

Input Parameters: TaskRetrieveRequest

Argument

Type

Mandatory

Default

Description

sID

String

No. See Transaction Login.

“”

Analyst’s current Session ID

sLoginUserID

String

No. See Transaction Login.

“”

Analyst’s Login ID

sLoginPassword

String

No. See Transaction Login.

“”

Analyst’s Password

sDatabase

String

No. See Transaction Login.

“”

Name of the vFire system for logging in.

lEntityRef

Lookup Field

Yes

-

Reference number of the task to retrieve

aCustomParameters

Array

No

“”

See Defining Custom Parameters.

Return Values: TaskRetrieveResponse

Argument

Type

Description
     

Ret

APIReturn

Error/Warning Number

sMessage

String

Error/Warning Message

ResultSet

DataSet

ResultSet containing attribute details

TaskComplete Transaction

Input Parameters: TaskCompleteRequest

Argument

Type

Mandatory

Default

Description

sID

String

No. See Transaction Login.

“”

Analyst’s current Session ID

sLoginUserID

String

No. See Transaction Login.

“”

Analyst’s Login ID

sLoginPassword

String

No. See Transaction Login.

“”

Analyst’s Password

sDatabase

String

No. See Transaction Login.

“”

Name of the vFire system for logging in.

lEntityRef

Lookup Field

Yes

-

Reference number of the task to complete

yApproved

Yes/No

Yes

-

Indicate whether to Approve or Reject an Approval. Applies to Approval tasks only. Values:

  • Y = Approve approval task
  • N = Reject approval task

sActionDesc

String

No

“”

Task Action & Solution contents

sPassword

String

Yes

-

Approver’s password, used to approve/reject an Approval. Applies to Approval tasks only.

lSecurityProfile

Lookup Field

No

0

Security Profile

yPortal

Yes/No

No

N

Flag whether this Action & Solution is visible on the Self Service Portal. Values:

  • Y = this Action & Solution entry is visible on the Self Service Portal
  • N = this Action & Solution entry is not visible on the Self Service Portal

lActionType

Lookup Field

No

0

Action & Solution Type

dActionEnd

Date/Time

No

Now

Action & Solution end date

dActionStart

Date/Time

No

Now

Action & Solution start date

nHrs

Integer

No

Uses the difference between the Action Start and Action End

Action & Solution recorded time spent

nMins

Integer

No

Uses the difference between the Action Start and Action End

Action & Solution recorded time spent

nExpenses

Integer

No

0

Expenses associated with the Action & Solution

lTaskStatus

Lookup Field

No

0

Task Status

sReason

String

No

“”

Audit reason

aCustomParameters

Array

No

“”

See Defining Custom Parameters.

Return Values: TaskResponse

See TaskResponse for more information.

TaskForwardInt Transaction

The TaskForwardInt transaction can be used to forward an existing task internally to an analyst or group.

Input Parameters: TaskInternalRequest

Argument

Type

Mandatory

Default

Description

sID

String

No. See Transaction Login.

“”

Analyst’s current Session ID

sLoginUserID

String

No. See Transaction Login.

“”

Analyst’s Login ID

sLoginPassword

String

No. See Transaction Login.

“”

Analyst’s Password

sDatabase

String

No. See Transaction Login.

“”

Name of the vFire system for logging in.

lEntityRef

Lookup Field

Yes

-

Task to retrieve

lFwdOfficer

Lookup Field

No

0

Analyst to which to forward the task

lFwdGroup

Lookup Field

No

0

Group to which to forward the task

bSendEmail

Boolean

No

False

Flag whether to send an email to the task assigned analyst/group. Values:

  • True = send an email to the assigned analyst/group
  • False = do not send an email to the assigned analyst/group

bSendPager

Boolean

No

False

Flag whether to send a pager message to the task assigned analyst/group. Values:

  • True = send a pager message to the assigned analyst/group
  • False = do not send a pager message to the assigned analyst/group

aCustomParameters

Array

No

“”

See Defining Custom Parameters.

Return Values: TaskResponse

See TaskResponse for more information.

TaskCreateOutage Transaction

The TaskCreateOutage transaction can be used to create an outage against an item linked to a task.

Input Parameters: TaskCreateOutageRequest

Argument

Type

Mandatory

Default

Description

sID

String

No. See Transaction Login.

“”

Analyst’s current Session ID

sLoginUserID

String

No. See Transaction Login.

“”

Analyst’s Login ID

sLoginPassword

String

No. See Transaction Login.

“”

Analyst’s Password

sDatabase

String

No. See Transaction Login.

“”

Name of the vFire system for logging in.

lEntityRef

Lookup Field

Yes

-

Reference number of the task to retrieve

lCMDBItem

Lookup Field

Yes

-

CMDB item linked to the task in which to create an outage

lOutageType

Lookup Field

No

0

Outage type associated with the outage

dOutageEnd

Date/Time

No

Now

Outage end date

dOutageStart

Date/Time

No

Now

Outage start date

sOutageDesc

String

No

“”

Description of the outage to create

aCustomParameters

Array

No

“”

See Defining Custom Parameters.

Return Values: TaskResponse

See TaskResponse for more information.

TaskFindLinkedOutage Transaction

The TaskFindLinkedOutage transaction can be used to find outages linked to a given task.

Input Parameters: EntityBaseRequest

Argument

Type

Mandatory

Default

Description

sID

String

No. See Transaction Login.

“”

Analyst’s current Session ID

sLoginUserID

String

No. See Transaction Login.

“”

Analyst’s Login ID

sLoginPassword

String

No. See Transaction Login.

“”

Analyst’s Password

sDatabase

String

No. See Transaction Login.

“”

Name of the vFire system for logging in.

lEntityRef

Lookup Field

Yes

-

Reference number of the task to retrieve

aCustomParameters

Array

No

“”

See Defining Custom Parameters.

Return Values: TaskRetrieveResponse

See TaskRetrieveResponse for more information.

TaskTimesheetCreate Transaction

The TaskTimeSheetCreate transaction can be used to create a timesheet entry for an existing task.

Input Parameters: TaskTimesheetCreateRequest

Argument

Type

Mandatory

Default

Description

sID

String

No. See Transaction Login.

“”

Analyst’s current Session ID

sLoginUserID

String

No. See Transaction Login.

“”

Analyst’s Login ID

sLoginPassword

String

No. See Transaction Login.

“”

Analyst’s Password

sDatabase

String

No. See Transaction Login.

“”

Name of the vFire system for logging in.

lEntityRef

Lookup Field

Yes

-

Reference number of the task in which to add a timesheet entry

nHistoryOrder

Integer

Ignored

-

Ignored on create

lTimesheetAction

Lookup Field

No

0

Timesheet action

sHistoryDesc

String

No

“”

Timesheet history entry description

dStartDate

Date/Time

No

Now

Timesheet entry start date

dEndDate

Date/Time

No

Now

Timesheet entry end date

nExpenses

Integer

No

0

Timesheet expenses

yPortal

Yes/No

No

N

Flag whether to make this history entry visible on the Self Service Portal. Values:

  • Y = this entry is visible on the Self Service Portal
  • N = this entry is not visible on the Self Service Portal

lSecurityProfile

Lookup Field

No

0

Security profile to apply to this history entry

aCustomParameters

Array

No

“”

See Defining Custom Parameters.

Return Values: TaskResponse

See TaskResponse for more information.

TaskTimesheetUpdate Transaction

The TaskTimeSheetUpdate transaction can be used to update an existing timesheet entry.

Input Parameters: TaskTimesheetUpdateRequest

Argument

Type

Mandatory

Default

Description

sID

String

No. See Transaction Login.

“”

Analyst’s current Session ID

sLoginUserID

String

No. See Transaction Login.

“”

Analyst’s Login ID

sLoginPassword

String

No. See Transaction Login.

“”

Analyst’s Password

sDatabase

String

No. See Transaction Login.

“”

Name of the vFire system for logging in.

lEntityRef

Lookup Field

Yes

-

Reference number of the task in which to update a timesheet entry

nHistoryOrder

Integer

Yes

-

Reference number of the history entry to update

lTimesheetAction

Lookup Field

No

0

Timesheet action

sHistoryDesc

String

No

“”

Timesheet history entry description

dStartDate

Date/Time

No

Now

Timesheet entry start date

dEndDate

Date/Time

No

Now

Timesheet entry end date

nExpenses

Integer

No

0

Timesheet expenses

yPortal

Yes/No

No

N

Flag whether to make this history entry visible on the Self Service Portal. Values:

  • Y = this entry is visible on the Self Service Portal
  • N = this entry is not visible on the Self Service Portal

lSecurityProfile

Lookup Field

No

0

Security profile to apply to this history entry

aCustomParameters

Array

No

“”

See Defining Custom Parameters.

Return Values: TaskResponse

See TaskResponse for more information.

TaskTimesheetDelete Transaction

The TaskTimeSheetDelete transaction can be used to delete an existing timesheet entry. You cannot use this transaction to update other task fields.

Input Parameters: TaskTimesheetDeleteRequest

Argument

Type

Mandatory

Default

Description

sID

String

No. See Transaction Login.

“”

Analyst’s current Session ID

sLoginUserID

String

No. See Transaction Login.

“”

Analyst’s Login ID

sLoginPassword

String

No. See Transaction Login.

“”

Analyst’s Password

sDatabase

String

No. See Transaction Login.

“”

Name of the vFire system for logging in.

lEntityRef

Lookup Field

Yes

-

Task with the timesheet entry to delete

nHistoryOrder

Integer

Yes

-

Task timesheet entry to delete

lTimesheetAction

Lookup Field

No

0

Timesheet action

sHistoryDesc

String

No

“”

Timesheet history entry description

dStartDate

Date/Time

No

Now

Timesheet entry start date

dEndDate

Date/Time

No

Now

Timesheet entry end date

nExpenses

Integer

No

0

Timesheet expenses

yPortal

Yes/No

No

N

Flag whether to make this history entry visible on the Self Service Portal. Values:

  • Y = this entry is visible on the Self Service Portal
  • N = this entry is not visible on the Self Service Portal

lSecurityProfile

Lookup Field

No

0

Security profile to apply to this history entry

aCustomParameters

Array

No

“”

See Defining Custom Parameters.

Return Values: TaskResponse

See TaskResponse for more information.